home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 090 / cmln0286.arc / EDFILE.DOC < prev    next >
Text File  |  1986-02-03  |  20KB  |  417 lines
  1.                       EDFILE UTILITY USAGE
  2.                           Jan 10, 1984
  3.  
  4. by Mike Mosko, K3RL 
  5.  
  6. EDFILE  is  a  public  domain utility which  allows  display  and 
  7. editing of data in files.  It has been tested and run under CP/M-
  8. 80  version   2.2 and TurboDOS 1.2 and should run in any  CP/M-80 
  9. type environment.
  10.  
  11. EDFILE  is  approximately  11k  in size.  EDFILE  may  be  freely 
  12. distributed  to whomever desires it.  The date of  this  document 
  13. should  agree  with  the version date in  EDFILE.  
  14.  
  15. FEATURES:
  16. ========
  17.  
  18.      - Hex and ASCII display of record data.
  19.      - Screen editing of selected record.
  20.      - Hex or ASCII input when editing file records.
  21.      - Fully programmable cursor control.
  22.      - Powerful file search capabilities.
  23.      - Forward and backward record scrolling.
  24.      - Address and/or record number referencing.
  25.      - Decimal or Hex number inputs.
  26.      - Disk reset on input (prevents Disk R/O error).
  27.      - Full online abbreviated help AND expanded help menus.
  28.   
  29.  
  30. INSTALLATION:
  31. ============
  32.  
  33. The  following  information  will aid the  user  when  installing 
  34. EDFILE  on a different terminal.  
  35.  
  36. The EDFILE original distribution program is originally configured 
  37. for  an  ADM-3A  type  terminal or equivalent (I  use  a  Digilog 
  38. S1500).  The  terminal must be able to display 80 columns  by  24 
  39. rows.  The only absolutely necessary function required for proper 
  40. use   is  the  cursor  positioning  function.   Other   functions 
  41. that  can be added merely for visual purposes are the cursor  on, 
  42. cursor  off and clear to end-of-line functions.  If the clear  to 
  43. end-of-line  function is not preprogrammed,  it is  performed  in 
  44. software.  These  functions  are not implemented in the  original 
  45. distribution version of EDFILE.  For ADM-3A type  terminals,  the 
  46. following  commands can be patched in EDFILE if these  attributes 
  47. are desired:
  48.  
  49.      Clear to end-of-line .... ESC 'Q' (1B,51)
  50.      Enable Cursor ........... ESC 'X' (1B,58)
  51.      Disable Cursor .......... ESC 'Y' (1B,59)
  52.  
  53. For example, to add the clear to end-of-line function, patch a 02 
  54. for  the string length (2 bytes for the sequence) at address 146. 
  55. Then patch a 1B in location 147 and a 51 in location 148.
  56.  
  57. Certain  functions  are programmable for the type of terminal  in 
  58. use.  Five bytes are reserved for each terminal function  (string 
  59. sequence).  The  first  byte represents the length of the  string 
  60. sequence.  For example: the initial cursor positioning string for 
  61. an  ADM-3A  terminal is 'ESC ='.  This is two  bytes  in  length. 
  62. Therefore,  the  values  inserted  into  the  cursor  positioning 
  63. sequence  area  are (in hex):  02,1B,3D.  To complete the  cursor 
  64. positioning sequence for the terminal, the row and column must be 
  65. issued  as  well.  The ADM-3A requires an  adjustment  value  (or 
  66. offset)  of  32 decimal (20 hex) be added to the row and  column. 
  67. For terminals that require a different offset,  this value can be 
  68. changed  as  well.  
  69.  
  70. The row is usually sent before the column,  but if your  terminal 
  71. is different, i.e., the column must be issued first, then set the 
  72. high order bit of the cursor offset value.  This flags the cursor 
  73. positioning  routine  to  send the column before  the  row.   The 
  74. following  addresses  detail  the  location  of  the   modifiable 
  75. parameters for the terminal.
  76.  
  77. Address   Default (hex)    Function
  78. -------   -------------    --------
  79. 140       02,1B,3D,00,00  *Initial cursor positioning string sequence
  80. 145       20              *Row/column adjustment (set high bit for column/row)
  81. 146       00,00,00,00,00   Clear to end-of-line string sequence 
  82. 14B       00,00,00,00,00   Enable cursor (cursor on) string sequence 
  83. 150       00,00,00,00,00   Disable cursor (cursor off) string sequence 
  84. 155       08               Cursor left (normally CTRL-H)
  85. 156       0C               Cursor right (normally CTRL-L)
  86. 157       0B               Cursor up (normally CTRL-K)
  87. 158       0A               Cursor down (normally CTRL-J)
  88. 159       00..........00   Terminal initialization string (35 bytes)
  89.  
  90. * - Must be implemented.
  91.  
  92. If  your  terminal requires some sort of  initialization  string, 
  93. either to preset it or to program a function key pad, this can be 
  94. inserted  into the terminal initialization string area  provided. 
  95. The  first byte represents the length of the string to be  issued 
  96. to   the  terminal.   There  are  35  bytes  available   for   an 
  97. initialization string.  Why so many? The Digilog S1500 computer I 
  98. use allows reprogramming of the numeric keypad.  This requires 28 
  99. bytes. 
  100.  
  101. The  actual  control  sequences for positioning the  cursor  (up, 
  102. down,  left  and  right) can be changed.  This  is  provided  for 
  103. terminals  that have cursor positioning keypads which don't issue 
  104. the  same ones programmed here.  For example:  usually  a  CTRL-L 
  105. moves the cursor one space to the right.  However, if your cursor 
  106. pad issues some other control character,  like a CTRL-D (WordStar 
  107. type),  then patch a 04 (hex equivalent of CTRL-D) for the cursor 
  108. right value.  Note, the help menus will still display the default 
  109. values for up, down, left and right cursor movements. You'll have 
  110. to make a note about this or, better yet, use EDFILE to patch the 
  111. help menus.
  112.  
  113. All of the above modifications (patches) can be made easily  with 
  114. EDFILE itself.  Of course, if it won't run at all, you'll have to 
  115. resort  to  some sort of debugger  such  as  DDT,  SID,  MONITOR, 
  116. etc...,  or  better  yet,  use  someone  elses  computer  with  a 
  117. (working) version of EDFILE to modify it for your terminal.
  118.  
  119. EDFILE  should work on virtually all terminals currently in  use. 
  120. There  may be some real strange ones out there that I don't  know 
  121. about, but that's life. 
  122.  
  123.  
  124. OPERATION:
  125. =========
  126. EDFILE  is simple to use especially with the online  help  menus. 
  127. Therefore, just a few tidbits of information is provided here for 
  128. operation.  To invoke EDFILE,  simply type EDFILE followed by the 
  129. name of the file you wish to dump and/or edit.  Example:
  130.  
  131.           EDFILE EDFILE.COM
  132.  
  133. The display should look similar to the following:
  134.  
  135. -------------------------------------------------------------------------------
  136. Vers: 01-10-84; by: J.C.Kaltwasser & M.J.Mosko, K3RL
  137.  
  138. File: EDFILE.COM  Record: 00000 (0000H)   LOF: 00086 (0056H)
  139.         00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F       0123456789ABCDEF
  140.         -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --       ----------------
  141. 0100  - 31 EA 01 C3 EA 01 0D 0A 56 65 72 73 3A 20 30 31      >1j.Cj...Vers: 01<
  142. 0110  - 2D 31 30 2D 38 34 3B 20 62 79 3A 20 4A 2E 43 2E      >-10-84; by: J.C.<
  143. 0120  - 4B 61 6C 74 77 61 73 73 65 72 20 26 20 4D 2E 4A      >Kaltwasser & M.J<
  144. 0130  - 2E 4D 6F 73 6B 6F 2C 20 4B 33 52 4C 0D 0A 24 1A      >.Mosko, K3RL..$.<
  145. 0140  - 02 1B 3D 00 00 20 00 00 00 00 00 00 00 00 00 00      >..=.............<
  146. 0150  - 00 00 00 00 00 08 0C 0B 0A 00 00 00 00 00 00 00      >................<
  147. 0160  - 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00      >................<
  148. 0170  - 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00      >................<
  149. ?
  150. -------------------------------------------------------------------------------
  151.  
  152. EDFILE  performs  an  automatic disk reset  (^C)  when  executed. 
  153. Therefore,  don't  panic  if you suddenly realized you forgot  to 
  154. perform a Control-C after making some changes.  This prevents the 
  155. infamous (and frustrating) Bdos Err on A:  R/O from occuring when 
  156. writing records.
  157.  
  158. The  LOF  means the Length-Of-File which is the total  number  of 
  159. records  in  the  file.  Record  numbers begin  at  0;  the  last 
  160. displayable record number is actually the LOF - 1.
  161.  
  162. If  you don't specify a file on the command line,  you'll get  an 
  163. error:  "No File Specified."; or if the file is not found, you'll 
  164. get an error telling you this: "<filename> Not Found." Simple.
  165.  
  166. At the ? prompt, type 'H'. The brief help menu will be displayed:
  167.  
  168. -------------------------------------------------------------------------------
  169. Read/Edit File Utility Functions:
  170. A - Address to dump         B - Dump at beginning       C - Continue Search
  171. E - Enter Edit Mode         H - This help list          M - Expanded Help list
  172. O - Set address offset      Q - Quit this program       R - Read & dump record
  173. S - Search for string       Z - Dump at end of file     CR - (+/=) - Adv record
  174. (-/_) - Decr record   
  175.  
  176. Edit Mode Functions:
  177. ^E - Toggle data fields     ^W - Write buffer out       ^X - Abort Edit Mode  
  178. ^J - Cursor Down            ^K - Cursor Up              ^H - Cursor Left      
  179. ^L - Cursor Right     
  180. -------------------------------------------------------------------------------
  181.  
  182. Again at the ? prompt, type 'M'. This will display the expanded help menu.
  183.  
  184. -------------------------------------------------------------------------------
  185. Read/Edit File Utility Functions:
  186.     A - Enter relative address to dump 
  187.     B - Set record to beginning of file and dump data
  188.     C - Continue search. Restarts search on last entered search string.
  189.     E - Enter Edit mode on current record
  190.     H - Brief description of the functions
  191.     M - This help description
  192.     O - Enter offset address relative to start of file (.COM = 100h)
  193.     Q - Quit program
  194.     R - Enter record number to dump 
  195.     S - Search for hex or ASCII string in file (starts at current record)
  196.             '\' = ASCII string delimiters (ex: \Test\)
  197.             ',' = hex and/or ASCII delimiters (ex: 41,\Test\,4A
  198.             ';' = select search options
  199.                     A - Start search from beginning of file
  200.                     B - Search Backwards
  201.                     M - Search on certain bits set; use mask xx
  202.                     O - Stop on xx occurrence of string
  203.                     U - Translate lower case characters to upper case
  204.                     Z - Search recognition on least significant 7 bits only
  205.  
  206.     Z - Set record to end of file and dump data
  207.     CR - carriage return (or +/= key) - advances record and dumps the data
  208.     -/_ key - decrements record and dumps the data
  209. Edit mode: ('^' refers to the Control key)
  210.     ^[ - (ESC) Accept next char into edit field even if a control char
  211.     ^E - Toggle between ASCII and hex data fields
  212.     ^W - Flush record to disk
  213.     ^X - Abort edit mode without updating record
  214.  
  215.     ^J - Cursor down            ^K - Cursor up    
  216.     ^H - Cursor left            ^L - Cursor right    
  217. Input integers are decimal. Use 'h' suffix for hexadecimal entries.
  218. -------------------------------------------------------------------------------
  219.  
  220. Use  the '=' key (which has the '+') or the RETURN key to advance 
  221. the record. You don't have to use the shift key with the '=' key. 
  222. EDFILE will wrap around to the start of the file when  attempting 
  223. to advance beyond the end of the file.
  224.  
  225. The  following  paragraphs  expand on the features  available  in 
  226. EDFILE.  Most  of the options are self-explanatory from the  help 
  227. menus.  However,  some  require additional explanations  and  are 
  228. provided below.
  229.  
  230. ADDRESS/OFFSET OPTIONS
  231. ----------------------
  232. The  address option allows you to specify an address  within  the 
  233. file. This is useful for patching COM files and the like when the 
  234. address  of  the patch is known.  Note that when  EDFILE'ing  COM 
  235. files,  EDFILE automatically sets the offset to 0100h. The offset 
  236. can  be  changed by typing 'O' at the command level and  entering 
  237. the  desired  offset.  The  headings  will be  adjusted  for  the 
  238. different   offset  automatically.   The  address  option  always 
  239. references  the starting offset so that locations within programs  
  240. which don't begin at 0100h (overlays,  for example) can be easily 
  241. referenced  once  the offset has been  properly  programmed.  The 
  242. Address option also has a wrap-around feature so that  references 
  243. below the current offset will be readjusted.  This feature can be 
  244. quite  handy  when tinkering around with COM files.  You have  to 
  245. experiment a little to pickup the usefulness of these options.
  246.  
  247. SEARCH OPTION
  248. -------------
  249. The  'search'  option is the most involved because it  offers  so 
  250. many different possibilites. The description provided here should 
  251. provide enough information to effectively use it. 
  252.  
  253. String  searches  normally  start  from the  current  record  and 
  254. proceed  until the end of the file (EOF) is encountered.  Certain 
  255. suboptions can alter this sequence.  If a match is not found, the 
  256. program  will indicate this and restore the screen to the  record 
  257. last  displayed.  The search can be aborted at any time by simply 
  258. striking a key.
  259.  
  260. If a string match occurs across records,  the search will stop on 
  261. the  last  record  read into its' local buffer and  position  the 
  262. cursor  at  the end of the found string.  It  just  wasn't  worth 
  263. putting in the extra code to handle this wierd situation.
  264.  
  265. When  using the Occurrence ('O') and Mask ('M')  suboptions,  the 
  266. program will prompt for the occurrence number and/or search  mask 
  267. to  be  used.  The suboptions are inserted after a  semicolon  to 
  268. delimit them from the search string entered.  No spaces should be 
  269. inserted   between  the  suboptions.   Upper  or  lower  case  is 
  270. acceptable. Example:
  271.  
  272.      ?Search String = \This is great\;auo
  273.      Stop on string occurrence = 3
  274.  
  275.   This  means to search for the string 'This is  great'  starting   
  276.   from    the  beginning of the file,  ignoring the case  of  the 
  277.   string  (i.e.,  translate lower to upper case) and stopping  on 
  278.   the third occurrence of the string.
  279.  
  280. ASCII  strings  must  be delimitted  by  backslashes  ('\').  The 
  281. limitation  here,  of  course,  is  that  you  can't  search  for 
  282. backslashes in the file.  So use the hex equivalent if necessary: 
  283. 5C.
  284.  
  285. The  'U'  suboption  (translate lower case to  upper  case)  will 
  286. translate the search string to upper case automatically,  as well 
  287. as  converting all lower case characters read from the file.  So, 
  288. you  don't  have to input the search string in  upper  case  when 
  289. using the 'U' suboption.
  290.  
  291. When  inputting hexidecimal values as part of a search key,  they 
  292. MUST be two-digit HEX (not decimal) numbers. An invalid hex digit 
  293. entry will cause an error and the string entry must be reentered. 
  294. Two  digits  must be supplied for each hex number  otherwise  the 
  295. search  won't  work  properly.   Upper  or  lower  case  for  the 
  296. hexidecimal letters is acceptable. Example:
  297.  
  298.      ?Search String = 40,FE,e5,05
  299.  
  300. You  can  mix hex entries with string entries within  the  search 
  301. key. Example:
  302.  
  303.      ?Search String = 40,FE,\help me\,E5,05
  304.  
  305. The  Backward search suboption (B) will start the search from the 
  306. current  record and continue towards the start of  the  file.  It 
  307. DOES  NOT reverse the search string key,  that is,  if you  enter 
  308. \HELP\ for a search string key,  it will not search backwards for 
  309. \PLEH\.  It only refers to the direction the records will be read 
  310. while  searching  for a matching string.  Also,  each  record  is 
  311. searched from the start of the record.  The search stops when the 
  312. start of the file (SOF) is encountered.
  313.  
  314. The  Mask suboption is for those cases where bytes in a file  use 
  315. certain  bits for special meanings.  The input mask is  logically 
  316. AND'd  with  each  byte in the file before comparing  it  to  the 
  317. search string.  Therefore,  some bytes could pass the search test 
  318. but still may not be exactly what your looking for.
  319.  
  320.      ?Search String = 03;M
  321.      Enter string search mask = 0Fh
  322.  
  323.   This  will  mask all upper nibbles (upper 4 bits of each  byte) 
  324.   and  then compare it to a 3.  Therefore,  any data bytes  which 
  325.   have a 3 in the lower nibble will cause a match with the search 
  326.   key.
  327.  
  328. When  the  search  string is found in the  file,  the  search  is 
  329. temporarily  terminated and the cursor is positioned at the start 
  330. of the found string.  Note,  that the program is NOT in the  edit 
  331. mode,  so  the next key entered is a command not an edit  control 
  332. key.  Hit  a space (or any unrecognizable command) to redump  the 
  333. record and place the cursor on the command line. Hit an 'E' to go 
  334. into  the  edit mode.  The cursor will remain positioned  at  the 
  335. start of the found string. 
  336.  
  337. CONTINUE SEARCH OPTION
  338. ----------------------
  339. Hitting  a 'C' at the command level will restart the search  from 
  340. the  current record and cursor position (if previously  defined). 
  341. The search facility will then look for the NEXT occurrence of the 
  342. entered  string sequence.  The 'O' suboption is affective only on 
  343. the  initial  start  of the search.  The  Continue  ('C')  option 
  344. effectively disables the occurrence value previously entered. The 
  345. default  string  occurrence  is 1,  i.e.,  the  first  (or  next) 
  346. occurrence.  The Continue option can be invoked at any time after 
  347. a search string key has been entered. All other suboptions are in 
  348. affect when continuing the search.
  349.  
  350.  
  351. RECORD EDITING
  352. --------------
  353. Record  editing is accomplished by typing an 'E' at  the  command 
  354. level. When in the edit mode, there are two modes of editing. You 
  355. can  edit  the HEXIDECIMAL field area of the record or the  ASCII 
  356. field  area.  When  entering  the edit mode the  cursor  will  be 
  357. positioned at the upper left corner in the HEX data field of  the 
  358. current record.  To switch to the ASCII data field of the record, 
  359. simply  enter a CTRL-E.  This will toggle the cursor between  the 
  360. two  fields.  The  HEX field area will  only  accept  hexidecimal 
  361. digits  for  inputs.  The ASCII field will accept all key  inputs 
  362. including control key inputs if they are preceeded by an ESC key.
  363. For  example:  to input a CTRL-K into the record at  the  current 
  364. cursor position,  hit the ESC key followed by a CTRL-K.  The  ESC 
  365. key  simply  means 'put the next input character into the  record 
  366. even if its' a control character'.  This is only affective in the 
  367. ASCII  field area.  Non-control characters (i.e.,  regular ASCII) 
  368. can be typed in directly.
  369.  
  370. To make the record changes permanently to the file,  they must be 
  371. flushed to the disk by typing a CTRL-W. Typing a CTRL-X will exit 
  372. the edit mode without updating the file. 
  373.  
  374. BUGS:
  375. ====
  376. There  are  currenly  no  know  bugs.  However,  inputs  are  not 
  377. completely  validated,  therefore,  some conditions  could  cause 
  378. different results.  None, however, are know to cause file crashes 
  379. or  anything catastrophic.  Any reports of bugs will be noted and 
  380. appreciated. 
  381.  
  382. USE UNDER TURBODOS:
  383. ==================
  384. EDFILE  is especially useful under TurboDOS.  Using the  filename 
  385. $.DSK  or  $.DIR upon entering EDFILE allows editing of the  disk 
  386. and/or directory.  I use EDFILE in every case when I need to look 
  387. at the disk directory and make changes to it. The search facility 
  388. makes this task a breeze.
  389.  
  390. BACKGROUND INFO:
  391. ===============
  392. EDFILE   was   written  in  a  language   called   SIL   (Systems 
  393. Implementation  Language)  which was obtained from DDJ  and  then 
  394. enhanced and improved at Digilog,  Inc for use in writing systems 
  395. programs  and  utilities.  SIL is very similar to 'C' but  allows 
  396. true  inline 8080/Z80 assembly language coding (very useful)  and 
  397. compiles to actual assembly mnemonics. The output of the compiler 
  398. is  passed to Digital Research Inc's Relocatable Assembler (RMAC) 
  399. and then to DRI's Linker (LINK).  No special tricks were used  in 
  400. this program; that is, no system specific calls or locations were 
  401. referenced,  therefore,  it should run on any CP/M or  equivalent 
  402. system.  Of course,  Murphy is lurking around, so don't depend on 
  403. that assumption.
  404.  
  405. FUTURE VERSIONS:
  406. ===============
  407. On  the wish list is to add the capability to read and  edit  the 
  408. data  off of the disk on a track/sector basis.   Any other  ideas 
  409. will be seriously considered in future versions of EDFILE.
  410. Thanks and good EDFILE'ing. 
  411.  
  412. Problems,  suggestions  or  questions  can be sent to  me  on  my 
  413. CompuServe number (#72345,1540) or via my home address:
  414.      Mike Mosko
  415.      519 E. Station Ave.
  416.      Coopersburg, PA 18036
  417.